fix(plugin-audit): declare preserveAudit on the read-audit ledger write so record-view rows keep the VIEW instant - #16996

Fixes #16829

Clause-②: no

sys_audit_log's record_views rows answer "when did this user look at this record?". Read auditing batches its INSERTs off the request path by design, so buildRow writes created_at: event.viewedAt rather than letting the column's NOW() default stamp a whole batch with one drain timestamp — up to flushIntervalMs after the fact, with read order inside the window destroyed.

persistReadAuditRows wrote that row under { context: { isSystem: true } }, and the module's comment cited that flag as what carried the view instant through. It never was.

Re-measured on this tree, not inherited

Triage confirmed the anchors on origin/main e08892da; re-measured here at b834b48e7 (branch point). Four of five sit where triage left them; one moved by a line.

Confirmed independently: sys_stamp_audit_update passes isInsert: false into applyToRecord, whose created_at assignment is inside if (isInsert). That case is green whatever the insert path does, so it never covered the reliance it was cited for.

The change

await engine.insert(
  'sys_audit_log',
  rows as any,
  { context: { isSystem: true, preserveAudit: true } } as any,
);

Both keys, for two different layers. isSystem still carries the readonly-strip exemption the row needs; preserveAudit is the one the stamp hook reads. preserveAudit is the ruled historical-import channel (#3493, reaffirmed by #15964's ruling of 2026-09-06) — 「the door audit left open for reinstating an original timeline, not a bypass of it」 — and a view row's original timeline is the moment of the view, so this use sits inside its declared purpose.

The test is the substantive half, and it was RED first

packages/plugins/plugin-audit/src/read-audit-view-instant-preservation.integration.test.ts — a real ObjectKernel + real ObjectQLPlugin (which is what registers sys_stamp_audit_insert) + real SqliteWasmDriver, read back through the driver's own SQL surface. Shape copied from #16312's packages/runtime/src/notification-migration-audit-preservation.integration.test.ts, not reinvented.

RED before the change — the card's case only:

× a record-detail view is stamped with the VIEW instant, not the flush instant
AssertionError: expected 1788912779588 to be 1551675967891
   Tests  1 failed | 2 passed (3)

1551675967891 is 2019-03-04T05:06:07.891Z, the view instant. 1788912779588 is the drain instant of that run.

GREEN after — Tests 3 passed (3); whole package Test Files 23 passed (23) · Tests 326 passed (326).

The two passing cases are anti-vacuity controls, green on both sides on purpose:

1. a bare isSystem write does NOT keep a supplied created_at — the card's central claim, asserted on the very write path the ledger uses. It is also the proof the real hook is live in this fixture: in a hook-less harness this is the case that goes red first, by name.
2. context.preserveAudit DOES keep it, on this object and this write path — so a green third case means "the writer declared the channel", not "nothing was ever going to restamp this row".

Why a new file rather than the case that already claimed this

read-audit.test.ts has had a case named records the VIEW instant, not the flush instant since #8992. Its engine is a bare new ObjectQL() over a stub driver — no ObjectQLPlugin, therefore no audit stamp hook at all. It is green before #15964, green with the defect live, and green after this change: an instrument that cannot fail. That is the same shape that let migrate-sys-notification-to-event.test.ts read 23 passed for #16312 while the rows were being restamped.

That case is kept but demoted to what it can actually witness — that the writer puts viewedAt on the row it hands the engine — and both its docblock and the file header are corrected. The header previously claimed a third pin this file cannot make, in the same words the source comment used, so leaving it would have kept the false premise alive in a second place.

The comment repair

The comment at the created_at field cited engine-audit-anchor-write.test.ts's "a system-context write is still exempt" as authority. Both halves were wrong: isSystem exempts a write from the readonly strip and has never been read by the stamp hook, and the cited case is an engine.update. It is replaced with the real mechanism, a pointer to the write that carries it, and a note that what was truly carrying the value was the hook's pre-#15964 line record.created_at = record.created_at ?? now.

Three commits of harness plumbing, each forced by a measured gate failure

⚠️ These are not incidental — each was a red gate, and the remedy each took is the one that gate prescribes.

1. @objectstack/driver-sqlite-wasm as a devDependency of plugin-audit. No cycle: the driver depends on core / driver-sql / spec, none of them on this package.
2. check:test-source-alias red — NEW unaliased artifact import(s). Anchored alias added to vitest.config.ts. Widening the shrink-only registry is explicitly not the remedy.
3. check:type-source-resolution red — NEW dist-resolved type import(s). paths rule added to tsconfig.json. Its precondition holds: rootDir here is ../.. (packages/) and the source sits at packages/drivers/driver-sqlite-wasm/src, so no TS6059 is owed.
4. typecheck then red with 4 × TS1470 — the paths rule puts the driver's source into whichever program resolves the specifier, and in the BUILD program it compiles under the root config's CommonJS-bound module setting, where knex-wasm-dialect.ts and wasm-connection.ts use import.meta. Tests now leave that program, exactly as plugin-approvals spells it, and tsconfig.test.json (module: esnext / moduleResolution: bundler — what vitest really runs) keeps them. Coverage is unchanged and re-measured: check:type-check-coverage green, check:test-typecheck 0 files / 0 errors.

Ablation — the case can fail, and the tree came back

Run from the committed fix, under a trap ... EXIT INT TERM, restoring with git checkout HEAD -- ABSPATH (never the bare form, which restores from the index).

HEAD blob        : f202954dad80a99d008e1c703a26abea8765114e
BEFORE  anchorA(preserveAudit present)=1  anchorB(bare isSystem)=0
hash before      : f202954dad80a99d008e1c703a26abea8765114e
AFTER   anchorA(preserveAudit present)=0  anchorB(bare isSystem)=1
hash after       : 082ac545e7e07f2c14f310de5fb06f411582bc94
ON-DISK PROOF    : OK (anchor counts flipped 1/0 -> 0/1; blob differs from HEAD)
ABLATED RUN exit : 1
AssertionError: expected 1788914642949 to be 1551675967891
      Tests  1 failed | 2 passed (3)
hash restored    : f202954dad80a99d008e1c703a26abea8765114e
git diff HEAD    : EMPTY
RESTORE PROOF    : OK (empty git diff HEAD; blob equals the HEAD blob)
RESTORED RUN exit: 0
      Tests  3 passed (3)

Only the card's case moved; both controls stayed green under the mutation, so the ablation is targeted rather than a blanket break. No dist preflight is owed here: the mutated subject is reached by a relative in-package import (./read-audit.js), so vitest resolves it from src — which the RED itself demonstrates.

Gates

Derived from a fresh tree after merging origin/main (fe2b7554a), reconciled mechanically:

Run reconciliation — 70 derived, 70 run, 0 NOT-MEASURED, 0 UNRUN.
✓ dispatch-gates --ran: 70 derived famil(ies) accounted for — 70 run, 0 NOT-MEASURED.

Three gates first came back exit 3 PREREQUISITE NOT MET, which is NOT a pass and was not reported as one: check:dual-build-cjs-loads, check:i18n and check:type-check-debt all read built output. A full workspace build (turbo run build --filter='./packages/*' --filter='./packages/*/*', 72/72 successful) was run and all three re-run to real verdicts — green.

Beyond the derived union: pnpm lint (whole repo, exit 0 — no narrowing claimed and none needed), pnpm --filter @objectstack/plugin-audit typecheck, pnpm --filter @objectstack/plugin-audit test, and the three artifact-roster families whose roster sits in a directory this diff is in (check:authz-resolver, check:error-code-casing, check:filter-alias-parity) — all green, since their silence is not evidence in either direction.

pnpm check:route-envelope was run explicitly (green), per its known absence from the derived union (#16828). It does not in fact apply: every file in this diff contains zero c.json( / res.json( / ctx.json( call sites, measured per file.

⚠️ check:partof-closing-keyword will be RED on this PR, and no author action clears it. The first commit on this branch carries a card-relation trailer in its message, which the contract puts in the PR body only. It was pushed before the mistake was noticed, and this repository forbids amend / rebase / force-push — the gate's own text says so and says the red is then to be READ rather than acted on. Recorded here rather than left for a reviewer to discover. The relation itself is correct and unambiguous: the trailer names this same card and nothing else, and the body above declares it once.

验收备注

Triage's acceptance criteria, carried verbatim:

1. 用例必须驱动真实的 sys_stamp_audit_insert 钩子 —— ⛔ 不是任何跳过钩子的替身。 → met: real ObjectKernel + ObjectQLPlugin + SqliteWasmDriver, with an explicit anti-vacuity control that goes red if the hook is not live.
2. 该用例在修复之前必须是红的（⇒ 先写测试、看它红、再修）。 → met: written first, observed red (expected 1788912779588 to be 1551675967891), then the change; both readings above, plus an ablation reproducing the red from the committed state.
3. 形状可以照抄 —— The sys_notification migration back-dates created_at through the create-side ?? that #15964 removes, so migrated inbox rows and receipts get the migration instant #16312 的 packages/runtime/src/notification-migration-audit-preservation.integration.test.ts。⛔ 不必重新发明。 → met: copied, including its three-reading structure and its two anti-vacuity controls.

And the two constraints the dispatch carried as binding:

• 两个 key 都要,理由不同 — both present; ⛔ neither swapped for the other.
• 注释同笔修复 — done, and extended to the sibling suite's docblocks, which carried the identical false premise about the identical field. Left alone they would have handed the next reader exactly what triage said to remove.

Third-site sweep — the extra deliverable

Re-ran (not inherited) the eight-row created_at enumeration whose incompleteness produced this card. Result: no third RELIANT site; exactly two exist and both are known. Posted to #16312 with the method, the positive control, and the four sites that table omitted: #16312 (comment)

⚠️ The method matters more than the count: a textual window around each insert call — the obvious sweep — misses this card's own site, because persistReadAuditRows and buildRow are different functions ~50 lines apart. Reliance is a dataflow fact, not a proximity fact.

Out of scope — noted, not filed

• packages/services/service-storage/src/metadata-store.ts:321 builds { created_at: now, updated_at: now, ...rec } with the spread LAST, so a caller-supplied created_at would win and then be silently restamped by the hook. Not a defect today — both createFile callers supply none — and not a reproducible one, so ⛔ not filed. A latent channel of the same class, recorded here for whoever adds the third caller.
• The general shape behind both this card and The sys_notification migration back-dates created_at through the create-side ?? that #15964 removes, so migrated inbox rows and receipts get the migration instant #16312 is not the ??: it is a pin that claims an ENGINE guarantee from a harness that boots no engine. That is a repo-wide question about test-harness posture, not a defect, so ⛔ not filed as one.

🤖 Generated with Claude Code

https://claude.ai/code/session_012zTkyNHJ7TkuN2oXtP5x37

Generated by Claude Code